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PREFACE 



This is a temporary supplement to the MPE V Intrinsics Reference Manual. It is designed 
to cover all the intrinsics that are new or have been enhanced for MPE V releases 
E/F.00.00andG.00.00. 

While not designed as an update package , this temporary supplement should be used along 
with the MPE IV Intrinsics Reference Manual (30000-90010) to provide you a com- 
prehensive reference source for MPE V intrinsics. 

Currently the MPE V Intrinsics Reference Manual is undergoing a complete rewrite. In 
order to better serve you , we are trying to incorporate many of the comments and sugges- 
tions we have received via our Reader Comment Sheets and Service Requests. 
Unfortunately , the new Intrinsics Reference Manual is not ready for printing at the time 
of this software release. To meet your needs in the interim, we have compiled this tem- 
porary supplement to the MPE IV Intrinsics Reference Manual . 

We hope that this temporary supplement does not inconvenience you. Rest assured that 
the new MPE V Intrinsics Reference Manual (32033-90007) will soon be on its way to 
your office. It will be distributed via normal distribution channels. 
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CONVENTIONS USED IN THIS MANUAL 



NOTATION 



DESCRIPTION 



COMMAND 

KEYWORDS 
parameter 

parameter 
[ ] 



< > 



user input 



superscript 



Commands are shown in CAPITAL LETTERS. The names mus 
contain no blanks and be delimited by a non -alphabetic character 
(usually a blank). 

Literal keywords, which are entered optionally but exactly as 
specified, appear in CAPITAL LETTERS . 

Required parameters, for which you must substitute a value, ap- 
pear in bold italics. 

Optional parameters, for which you may substitute a value, appear 
in standard italics. 

An element inside brackets is optional. Several elements stacked in- 
side a pair of brackets means the user may select any one or none of 
these elements . 

Example: [ A ] , 

j. „ , user may select A or B or neither. 

When brackets are nested, parameters in inner brackets can only be 
specified if parameters in outer brackets or comma place-holders 
are specified. 
Example : Iparml I ,parm2 C ,parm3 ] ] ] may be entered as : 

parml,parm2,parm3 or 
parml ii parm3 or 
>:> parm3 , etc. 

When several elements are stacked within braces the user must 

select one of these elements. 

Example: i. A } , , 

, „ , user must select A or B. 

An ellipsis indicates that a previous bracketed element may be 
repeated, or that elements have been omitted. 

In examples of interactive dialog , user input is underlined . 
Example: NEW NAME? STICK2 

Control characters are indicated by a superscript . Example: Y C . 
(Press Y and the CNTL key simultaneously.) 



( 1 

<<C0MMENT>> 
** Comment ** 



c 



indicates a terminal key. The legend appears inside. 



Programmer's comments in listings appear within << >> . 
Editor's comments appear in this form. 
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FCLOSE 

INTRINSIC NUMBER 8 



Closes a file. 

SYNTAX 



IV IV IV 

FCLOSE (f ilenum, disposition i seccode') ; 



The FCLOSE intrinsic terminates access to a file. This intrinsic applies to files on all devices. FCLOSE 
deletes buffers and control blocks through which the user process accessed the file. It also deallocates 
the device on which the file resides and it may change the disposition of the file. If you do not issue 
FCLDSE calls for all files opened by your process, such calls are issued automatically by MPE when the 
process terminates. All magnetic tape files are left off line after such FCLOSE calls, to indicate to the 
System Operator that they may be removed. 

The FCLOSE intrinsic can be used to maintain position when creating or reading a labeled tape file 
that is part of a volume set. If you close the file with a disposition code of 3, the tape does not 
rewind , but remains positioned at the next file . If you close the file with a disposition code of 2 , the 
tape rewinds to the beginning of the file but is not unloaded. A subsequent request to open the file 
does not reposition if the sequence (seq) subparameter of formmsg in FOPEN specifies NEXT or 
default (1). A disposition code of 1 (rewind and unload) implies the close of an entire volume set. 

If an unlabelled magnetic tape is closed with a disposition code of , 1 , or 4 , and the tape was written 
to while open, FCLOSE writes three EOFs at the end of the tape before performing a rewind or 
rewind/unload. This ensures that all tapes have an acceptable number of EOF marks at the end. The 
three EOFs are written only after the last FCLOSE to occur before the rewind, and only if the tape 
was written on . 

For circular files, deletion of disc space beyond the end -of -file is not allowed. 



PARAMETERS 

filenum 
disposition 



integer by value (required) 

A word identifier supplying the file number of the file to be closed. 

integer by value (required) 

Indicates the disposition of the file, significant only for files on disc and 
magnetic tape [disposition is ignored by the Foreign Disc Facility). This 
disposition can be overridden by a corresponding parameter in a :FILE 
command entered prior to program execution. The disposition options are 
defined by the bit fields ( 1 3 : 3) and ( 1 2: 1 ) as follows: 



(13:3) Domain Disposition 

=000 No change. The disposition code remains as it was before the file 
was opened. Thus, if the file is new, it is deleted by FCLDSE ; 
otherwise, the file is assigned to the domain to which it belonged 
previously. An unlabeled tape file is rewound . If the file resides on 
a labeled tape , the tape is rewound and unloaded . 

=001 Permanent file. If the file is a disc file, it is saved in the system 
file domain. A new or old temporary file on disc will have an entry 
created for it in the system file directory. Should a file of the same 
name already exist in the directory, an error code is returned and 
the file remains open. If the file is an old permanent file on disc, 
this domain disposition has no effect. Also, if the file is stored on 
magnetic tape , that tape is rewound and unloaded . 

=010 Temporary job file (rewound). The file is retained in the user's 
temporary (job/session) file domain and can be requested by any 
process within the job/session. If the file is a disc file, the unique- 
ness of the file name is checked. Should a file of the same name al- 
ready exist in the temporary file domain , an error code is returned 
and the file remains open. When a file resides on unlabeled mag- 
netic tape, the tape is rewound. However, if the file resides on 
labeled magnetic tape, the tape is backspaced to the beginning of 
the presently opened file . 

=011 Temporary job file (not rewound). This option has the same effect 
as domain disposition 010, except that tape files are not rewound. 
In the case of unlabeled magnetic tape , if this FCL0SE is the last 
done on the device (with no other FOPEN calls outstanding) the tape 
is rewound and unloaded. If the file resides on a labeled magnetic 
tape , the tape is positioned to the beginning of the next file on the 
tape. 

= 100 Released file. The file is deleted from the system. 

(12:1) Disc Space Disposition (for fixed, undefined, and variable format 
files . 

=0 Does not return any disc space allocated beyond the end-of-file 
indicator. 

= 1 Returns to the system any disc space allocated beyond the end-of-file 
indicator. The EOF becomes the file limit. No records may be added 
to the file beyond this new limit. 

Bit (0:12) are reserved for MPE and should be set to zero. 

When a file is opened by the FDPEN intrinsic , a file count (maintained by 
MPE for each file) is incremented by one. When the file is closed, the file 
count is decremented by one. If more than one FDPEN is in effect for a 
particular file , its disposition is saved but not affected by the FCL0SE call 
until the file count is decremented to zero. Then the effective (saved) 
disposition is the smallest nonzero disposition parameter specified among all 



FCLOSE calls issued against the file. For example, the file XYZ is opened 
three successive times by a process. The first FCLDSE disposition is 1 , the 
second FCLOSE disposition is %14, and the third (and last) FCLDSE disposi- 
tion is %12. The final disposition on the file XYZ will be disposition 1 
(permanent file and no return of disc space). 

seccode integer by value (required) 

Denotes the type of security initially applied to the file , this is significant 
only for new permanent files {secode is ignored by the Foreign Disc 
Facility). The options are : 

Unrestricted access: the file can be accessed by any user, unless 
prohibited by current MPE provisions. 

1 Private file creator security: the file can be accessed only by its 

creator. 

CONDITION CODES 

CCE The file was closed successfully. 

CCG Not returned by this intrinsic. 

CCL The file was not closed, perhaps because an incorrect filenum was specified 

or because another file with the same name and disposition exists in the sys- 
tem. Any outstanding write I/O's which failed will also cause the FCLOSE 
to fail (such I/O's as buffered writes which are done in background). 
Additionally, an illegal disposition (5, 6, or 7) may have been specified. 
This can be detected by FCHECK returning an error of 49 . 

SPECIAL CONSIDERATIONS 

Split -stack calls permitted. 

ADDITIONAL DISCUSSION 

Communicator 3000 Volume 2 Issue 1 (5955-1770) 

For further information on magnetic tape files and associated functions, refer to the MPE File System 
Reference Manual (30000-90236). 



FFILEINFO 

Provides access to file information. 

SYNTAX 



0-V IV 


IV BA 


FFILEINFOCftlenum 


[ , itemmtml , itemoaluel ] 




C ,itemnum2 sitemoalueZ 1 




[ , itermumd , itemoalueZ j 




C , itetmum4 , xtemoaluei ] 




[ ,itemnumS ,itemoalue5 1 ) ; 



Itemnum/itemvalue parameters must appear in pairs. Up to five items of information can be 
retrieved by specifying one or more itemnum/itemvalue pairs. FFILEINFO is designed to allow for fu- 
ture changes so that new file information can be defined and accessed. 



PARAMETERS 

fxXevtuKi 

itemnum 
itemoalue 



integer by value (required) 

MPE file number returned by FOPEN . 

integer by value (optional) 

Cardinal number of the item desired; this specifies which item value is to 

be returned. (Refer to "ITEM #", Table 1.) 

byte array (optional) 

Returns the value of the item specified by the corresponding itemnum ; the 
data type of the item value depends on the item itself. (Refer to "ITEM" , 
Table 1.) 



CONDITION CODES 

CCE No error. 

CCG Not used. 

CCL Access or calling sequence error. 



ADDITIONAL DISCUSSION 

Communicator 3000 Volume 2 Issue 1 (5955-1770) 
MPE File System Reference Manual (30000-90236) 



Table 1 . Item Values Returned by FFILEINFO 



ITEM* 


ITEM 


TYPE 






UNITS 




1 


Filename 


BA 


(see 


FGETINFO) 






2 


Fopt ions 




( see 


FQETINFO) 






3 


Aopt ions 




(see 


FGETINFO) 






4 


Record 




( see 


FGETINFO) words/bytes 




5 


Device type 




(see 


FGETINFO) 






6 


Logical device number 




(see 


FGETINFO) 






■j 


Hdaddr 




(see 


FGETINFO) 






8 


File code 




(see 


FGETINFO) 






9 


Record pointer 


D 


( see 


FGETINFO) 






10 


EOF 


D 


(see 


FGETINFO) 






11 


File limit 


D 


(see 


FGETINFO) 


records 




12 


Log count 


D 


(see 


FGETINFO) 


records 




13 


Physcount 


D 


( see 


FGETINFO) 


records 




14 


Block size 


I 


(see 


FGETINFO) 


-ecords/bytes 




15 


Extent size 


L 


( see 


FGETINFO) 


sectors 




16 


Number of extents 


I 


(see 


FGETINFO) 






17 


User labels 


I 


( see 


FGETINFO) 






18 


Creator ID 


BA 


(see 


FGETINFO) 






19 


Label address 


D 


(see 


FGETINFO) 






20 


Blocking factor 


I 


(see 


FOPEN) 






21 


Physical block size 


I 






words 




22 


Data block size 


I 






words 




23 


Offset to data in blocks 


I 






words 




24 


Offset of Active Record Table 


I 


(RIO 


files) 


words 




25 


Size of Active Record Table 
within the block 


I 






words 




26 


Vol. ID(label tape) 


BA 


(see 


Label Tapes) 






27 


Vol. set IDdabel tape] 


BA 


(see 


Label Tapes) 






28 


Expiration date(Julian) 


I 


(see 


Label Tapes) 






29 


File sequence number 


I 


( see 


Label Tapes) 






30 


Reel number 


I 


(see 


Label Tapes) 






31 


Sequence type 


I 


(see 


Label Tapes) 






32 


Creation date (Julian) 


I 


(see 


Label Tapes) 







Table 1. Item Values Returned by FFILEINFO (Continued) 



v/e ^ 



ITEM* 
33 
34 
35 
36 
37 
38 



39 
40 
41 
42 
43 
44 
45 
46 
47 
48 



50 
51 
52 
53 
54 
55 
56 
57 
58 
59 
60 



BA 



BA 



ITEM 
Label type 
Current* of writers 
Current* of readers 
File Allocation Date 
File Allocation 
SP00LFILE Device file number 
(*0 or #1 number. If 
device is not spooled, 
intrinsic returns zero) 
RESERVED 

Disc or diskette device status 
Device type 
Device subtype 
Environment file name 
Last disc extent allocated 
Filename from labeled tape HDR1 record 
Tape density 
DRT number 
UNIT number 

Software interrupt PLABEL 
Real device number of the file 
Virtual device number 
Last modification time (CLOCK format) 
Last modification date (CALENDAR format) 
File creation date (CALENDAR format) 
Last access date (CALENDAR format) 

# data blocks in a variable length file 

# of the user label written to the file 
Number of opens for output 
Number of opens for input 
Terminal type, defined as: 

0-file's associated device is not a terminal 
1-standard hardwire or multi-point terminal 
2-the terminal is connected via a phone-modem 
3-DS psuedo terminal 
4-X.25 Packet Switching Network PAD 

(Packet Assembler Disassembler) terminal 



TYPE 


UNITS 


I 


(see labeled tapes) 


I 


(see IPC) 


I 


(see IPC) 


L 


(CALENDER format) 


D 


(CLOCK format) 


L 


(see File Code) 



FINTEXIT 

INTRINSIC NUMBER 23 



Returns from the user's interrupt procedure. 

SYNTAX 



0-V LV 

FINTEXIT tint state ); 



The FINTEXIT intrinsic returns from the user's interrupt procedure. Software interrupts are set ac- 
cording to intstate. If intstate is omitted, FINTEXIT. defaults to software interrupts enabled. 



PARAMETERS 



intstate 



logical by value (optional) 

A logical value indicating the state of software interrupts through bit 

( 1 5 : 1 ) as follows : 

=0 Leave software interrupts disabled. 

= 1 Enable software interrupts. 
Default: (1S:1)=1. 



CONDITION CODES 



The condition code remains unchanged. 



FINTSTATE 

INTRINSIC NUMBER 24 

Enables/disables all software interrupts against the calling process. 

SYNTAX 



L LV 

oldstate : =FINTSTATECin*sfcrte) ; 



The software interrupt facility enables users to perform FREAD/FWRITE completion processing with 
their own interrupt procedure. An FREAD/FWRITE call is necessary to initiate the I/O request. Both 
of these intrinsics return to the user's process as soon as the request has been started. When the opera- 
tion completes, the user's program is trapped (or "interrupted") and goes to a user chosen interrupt 
procedure. This performs whatever processing is necessary and then resumes the user's original 
program. 

Soft interrupts are "armed" for a particular file by specifying the interrupt procedure's plabel in an 
FCQNTROL call with a controlcode of 48. Calling "FCONTROL 48" with a parameter of will disarm 
the software interrupt mechanism. The file is then accessed in the previous manner. 



NOTE 



MPE inhibits software interrupts just before entering an 
interrupt procedure. This is done to stop unwanted nest- 
ing of the interrupt procedures. Each interrupt proce- 
dure should call FINTEXIT (Refer to FINTEXITin this 
section) to re -enable other interrupts just before it exits. 

Software interrupts are normally automatically in- 
hibited before a Y c trap procedure. The trap procedure 
may elect to allow software interrupts, however, by 
calling the FINTSTATE intrinsic. The RESETCONTROL 
intrinsic will restore the process's interrupt state to its 
pre-Y c value (unless the trap procedure issues an 
FINTSTATE call, in which case RESETCONTROL makes 
no change). 

When the software interrupt is executed, Q-4 will contain the file number of the file that caused the 
interrupt . 

It is necessary to issue a call to the IODONTWAIT intrinsic against the file in order to complete the 
request. When reading the target parameter is ignored in the FREAD call. The data is moved to the 
array specified by the target parameter of IODONTWAIT. 

FUNCTIONAL RETURN 

oldstate logical 

The old state (enabled or disabled) of software interrupts is returned by this 
procedure. 



PARAMETERS 

intstate logical by value (required) 

A logical value enabling/disabling software interrupts as through bit (15:1) 

as follows : 

=0 Disable software interrupts. 

= 1 Enable software interrupts. 

CONDITION CODES 

The condition code remains unchanged. 

SPECIAL CONSIDERATIONS 

An uncompleted FREAD/FWRITE request may be aborted by issuing an FCQNTRQL call with a control- 
code of 43 (abort NOW AIT I/O). 

Limitations : 

• Only message files allow soft interrupts. 

• No more than one uncompleted FREAD/FWRITE may be outstanding for a particular file. 

• The interrupt is held off while the user is executing within MPE, with the following ex- 
ceptions: PAUSE and IOWA IT will allow the interrupt. The interrupt handler's return 
stack marker in this case will be set to reinvoke the intrinsic. 

• May not be used with remote files. 



GETDSEG 

INTRINSIC NUMBER 130 
Creates an extra data segment. 

SYNTAX 



L I LV 

GETDSEG (index, length, id) ; 



The GETDSEG intrinsic creates or acquires an extra data segment. The number of extra data segments 
that can be requested, and the maximum size allowed these segments, are limited by parameters 
specified when the system is configured. When an extra data segment is created, the GETDSEG in- 
trinsic returns a logical index number to the calling process. This index number is assigned by MPE 
and allows this process to reference the segment in later intrinsic calls. The GETDSEG intrinsic also is 
used to assign the segment the identity that either allows other processes in the job or session to share 
the segment, or that declares it private to the calling process. If the segment is sharable, other 
processes can obtain its logical index (through GETDSEG) and use this index to reference the segment. 
Thus, the logical index is a local name that identifies the segment throughout any process that ob- 
tained the index with the GETDSEG call . The logical index need not be the same value in all processes 
sharing the data segment. The identity, on the other hand, is a job-wide or session-wide name that 
permits any process to determine the logical index of the segment. If the intrinsic is called in user 
mode, then the data segment is initially filled with zeros. When GETDSEG is called in User Mode, all 
subsequent calls to intrinsics that use index must now be in User Mode. Likewise, when GETDSEG is 
called in Privileged Mode, all subsequent calls to intrinsics that use index must now be in Privileged 
Mode. 



PARAMETERS 

index 



length 



id 



logical (required) 

A word to which the logical index of the data segment, assigned by MPE, is 
returned . When GETDSEG is called in User Mode , index is a logical index of 
the assigned data segment; if an error is found, index will be set to 
%2000-%2003. When GETDSEG is called in Privileged Mode, index is the 
actual entry segment entry number for the data segment that was assigned. 

integer (required) 

The maximum size of the data segment requested , if the segment is not yet 
created, or the word to which the maximum size of the segment is return- 
ed, if the segment already exists. 

logical by value (required) 

A word containing the identity that declares the data segment sharable be- 
tween other processes in the job/session, or private to the calling process. 
For a sharable segment, id is specified as a nonzero value. If a data seg- 
ment with the same id exists already, it is made available to the calling 
process. Otherwise, a new data segment, sharable within the job/session, is 
created with this id. For a private data segment, an id of zero must be 
specified . 
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CONDITION CODES 

CCE Request granted. A new segment was created . 

CCG Request granted. An extra data segment with this identity exists already. 

CCL Request denied. An illegal length was specified (index is set to %2000), or 

the process requested more than the maximum allowable number of data 
segments (index is set to %2001 ), sufficient storage was not available for 
the data segment (index is set to % 2 00 2) or a stack expansion necessary to 
satisfy the request could not be done because the stack was frozen (index set 
to %2003). (Note that a stack expansion is usually not necessary to get an 
extra data segment), or not enough room in job definition table to make an 
entry for the extra data segment (index set to %2004). 



SPECIAL CONSIDERATIONS 

Data Segment Management (DS) capability required. 

ADDITIONAL DISCUSSION 

Commuicator 3000 Volume 2 Issue 1 (5955-1770) 
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JOBINFO 

INTRINSIC NUMBER 180 

Provides access to job/session related information. 

SYNTAX 



IV D LA IV LA I 
JOB I NFOCjsindjJSfmin, status [ ,itemnuml ,iteml ,errornuml 1 

C , i temnumZ , itemZ , errornum2 ] 
[ , itemnumS , itemS , errorrcuml ] 
[ , itenoium4 , item4 , exvornum4 1 
[ , itennumS > itemS , errornum5 ] ) ; 



JOBINFO provides access to information related to any job/session that is current to the system. This 
intrinsic is expandable, and is written so that the addition of further functionality will be straight 
forward . 



PARAMETERS 

jsind 



JSIhvtn 



status 



itemnum 



integer by value (required) 

One of the following integers indicating whether the JSftnnn denotes a ses- 
sion or job : 

1 JS#nnn is a job . 

2 JSftnnn is a session . 

double (required) 

A double value, 32 bits, identifying a job or session for which information 

will be retrieved . 

logical array (required) 

A two word logical array to report the overall success/failure of the call. 
Only the first word contains significant information. The success/failure 
of the call is indicated by the following returns : 

Successful call. All errornums equal zero. 

1 Semi -successful call. One or more errornurft(s) were returned with 
nonzero values. 

2 Unsuccessful call . All errornums were returned with nonzero values . 

3 Unsuccessful call. Syntax error in calling sequence. 

4 Unsuccessful call. Unable to retrieve JS#nnn. 

5 Process terminated. The process terminated during the start of 

retrieval. 

integer by value (optional) 

Cardinal number of the item desired. This specifies which item value is to 

be returned (Refer to "ITEM#" in Table 2). 
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item logical array (optional) 

Name of a reference parameter (whose data type corresponds to the data 
type for the desired information) to which the desired information is 
returned (Refer to "ITEM" in Table 2). 

All of possible itemnum and item parameters are output parameters with 
one exception. Item number 1 can be used for an input and output param- 
eter. Item number 1 is an input parameter only if the user is identifying a 
job or session by parsing a character string containing the logon id, 
[jsname Jusername .acctname. Otherwise, it is an output parameter. The 
maximum number of characters returned is twenty -six. The returned 
string will be left justified and padded with blanks. 

ervornum integer (optional) 

A returned integer specifying the success or failure of the retrieval of each 
item. The returned values are: 

Successful information retrieval . 

1 Invalid itemnum (item number). 

2 Desired information not pertinent to the given JSftnnn (e.g., user 
specifies a session number and wishes to know if a job had RESTART 
option). 

3 User has insufficient capability to access this information . 

4 The desired information is no longer available (e.g., returned when 
spoolfiles disappear). 

SPECIAL CONSIDERATIONS 

A user without System Manager (SM) or Account Manager (AM) capability can only retrieve infor- 
mation about the jobs/sessions logged on under the user name and account. A user with AM 
capability, but not SM capability will be restricted to access information concerning account sessions 
and jobs; a user with SM capability will be able to retrieve information concerning all sessions and 
jobs. The exception to the above security will be access to items which are normally available to the 
user, through MPE commands, who does not have any special capabilities. 

CONDITION CODES 

There are no condition codes on the traditional sense , but the status parameter can be thought of as a 
condition code. 

ADDITIONAL DISCUSSION 

Communicator 3000 Volume 2 Issue 1 (5955-1770) 



JOBINFO provides the user with three options to identify a job or session which is on the system. The 
three options are the following : 
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• Taking the caller's job/session as default. 

• Specifying a specific job/session number. 

• Specifying a logon id . 

To retrieve information about the job/session executing JOBINFD, the user must specify the ap- 
propriate jsind (1 for session, 2 for job) and a jsnnn of OD (double -word zero). Further, the itemnum 
of the first optional triple must not be a one (1) as this invokes option number three (described 
below). For example, to retrieve the logon id for the caller, from a session, a JOBINFD call might 
look like this : 



Where : 



JOBINFtK 1, jsnnn, STATUS, ,, ,1 Jsname , ERR0R1 ); 



Jsnnn must be OD. 



• Jsind is 1 since JDBINFD is executed from a session, and default to the caller's session 
for the logon id . 

• Jsname must be a logical array of 1 3 words . 

• The session's session number will be returned through jsnnn . 

• The second triple contains the itemnum of 1 . When using the default job or session, the 
first triple can not contain an itemnum equaling 1 . 

It is not possible to attempt a default call with jsind equaling 2 if JOBINFD is executed from a session. 
Likewise, it is not possible to call JDBINFD, attempting a default call, with jsind equaling 1 when 
JOB INFO is executed from a job. 

The user may identify a job or session by specifying the appropriate job/session number through 
jsnnn, along with the appropriate jsind. By supplying a non-zero jsnnn, the other two job/session 
identification options are over -ridden. Their is no restriction the use of any of the optional triples, or 
itemnums. An example of specifying a specific job/session number is a follows: 

JDBINFOC 2, jsnnn, STATUS, 1, jsname, ERRDR1 ); 

Where : 

• Jsind equals 2 and specifies that jsnnn is a job number . 

• Jsnnn is a job number. 

• Itemnum equals 1 denoting that the logon id of job number jsnnn is to be retrieved. 

The user may identify a job or session by specifying the appropriate job/session by supplying the ap- 
propriate logon id through the first optional triple. The user must supply the appropriate jsind and 
jsnnn must be OD. The logon id is specified through the first triple with itemnum equal to 1 , and item 
being a logical array containing the logon id (a character string). The logon id must be terminated by 
a binary zero (0). The maximum length of the logon id is twenty-six (26) characters, plus one (1) for 
the binary zero terminator. An example of this is as follows: 

JDBINFOC 2, jsnnn, STATUS, 1, LOGDN'ID, ERRDR1 ); 
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Where: 

• Jsind equals 2, denoting the logon'id supplied is that of a job. 

• Jsnnn equals OD. 

• The job number of the job denoted by LDGON 'ID will be returned through jsnnn. 

• The first triple is specified with an itemnum equal to 1 , a logical array LOGON'ID con- 
taining the logon id of a job (terminated by a binary 0), and an integer error return for 
the item. 

An example of initializing LOGON 'ID might be as follows: 

MOVE LOGON'IDCO) := "TEST JOB, LARRY . OSE" , Q ; 
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Table 2. Item Descriptions 



ITEM# 

1 

2 

3 

4 

5 

6 

7 

8 

9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 



ITEM (information returned) 
[JSNAMEJuser. account (See note 1) 
session/job name (See note 2) 
user name (See note 2) 
user logon group (See note 2) 
user account (See note 2) 
user home group (See note 2) 
session/job introduction time (See note 3) 
session/job introduction date (See note 4) 
input ldov/class name (See note 2) 
output ldev/class name (See note 2) 
current job step (See note 5) 
current number of active jobs 
current number of active sessions 
job input priority 
job/session number 
jobf ence 

job output priority 
number of copies 
job limit (system) 
session limit (system) 
job deferred (See note 6) 
main PIN - CI PIN for job/session 
original job-spooled (See note 6) 
RESTART option (See note 6) 
sequenced - job (See note 6) 
term code (See note 7) 
CPU limit 

session/job state (See note 8) 
user's local attributes 

$STDIN spoolfile number (See notes 9 & 10) 
$STDIN spoolfile status (See notes 9 & 11) 
$STDLIST spoolfile number (See notes 9 & 10) 
$STDLIST spoolfile status (See notes 9 & 11) 
length of current job step of item number 11 
:SET $STDLIST=DELETE invoked (See note 12) 
Job Information Table data segment number 



DATA 
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Table 2. Item Descriptions (Notes) 



1. 


Can be used as an input 


or output parameter. If used as an input param- 




eter, a maximum of 26 


ASCII characters, plus one for a binary ter- 




minator is allowed. 


The input string must be in the form of 




[ j sname ,] user. account. 


The wildcard character @ is not allowed. If 




used as an output parameter, the logical array must be 13 words long. 




Output is left-justified and padded with blanks. 


2. 


A ASCII output parameter. Logical arrays must be 4 words long output is 




left justified and padded with blanks. 


3. 


Returns a 32-bit doubl 
int rinsic . 


e word in a form to be used by the FMTCLOCK 


4. 


Returns a 16-bit logics 
int rinsic . 


1 word in a form to be used by the FMTCALENDAR 


5. 


Returns a maximum of 283 ASCII characters, and is the image of the com- 




mand currently executin 


g. The logical array must be long enough to ac- 




comodate the expected command image. 


6. 


Returns the values: - 


No 




1 - 


Yes 


7. 


Returns the values: - 


Regular terminal 




1 - 


Regular terminal with special log on. 




2 - 


APL terminal 




3 - 


APL terminal 


8. 


Returns the values : 2 - 


Executing 




4 - 


Suspending 




32 


- Wait 




48 


- Initialization 


9 , 


Returns data for curren 


t jobs and sessions. $STDIN/$STDLIST files only. 


10. 


Returns the spoolfile number as an integer. 


11. 


Returns the values: - 


Active 




1 - 


Ready 




2 - 


Open 




3 - 


Reserved 


12. 


Returns the values: - 


SSTDLIST will be saved. 




1 - 


:SET $STDLIST=DELETE is invoked. 
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PROCINFO 

INTRINSIC NUMBER III 
Provides access to process information. 

SYNTAX 



0-V I I IV I BA 

PRDC I WQ(.ervorl,errox>2 t pin i ,itemnuml ,iteml ] 

[ , i temxvmZ , item2 ] 
[ , itemnumS , itemd ] 
[ , itermicm4 , item4 ] 
C , itemnumS ,item5 ] 
[ , itemmanB , i tem6 ] ) ; 



PARAMETERS 

error! 

error2 
pin 



itemnum 



integer (required) 

An integer indicating the success or failure of the intrinsic call as described 

in Figure 1 . 



integer (required) 
An integer which 
reported in error I . 



supplies additional information 
It is also defined in Figure 1 . 



concerning an error 



integer by value (required) 

An integer specifying the process identification number for which informa- 
tion is to be returned. A pin value of zero will return information about 
the calling process. Note that it is not compatible with the pin parameter 
of the GETPRDC I NFD intrinsic. 

integer (optional) 

An integer containing the item number (in any order) of an information 
option as defined in Figure 2. The user may request up to 6 options to be 
returned . 



item 



byte array (optional) 

Arrays (in the same order as the itemnums) of returned information as 

specified in Figure 2. 

The parameters error I, error 2, pin are required. The itemnum and item 
parameters are optional. The actual number included depends upon the in- 
formation desired. The itemnums and the items are paired such that the 
nth itemnum corresponds to the nth item. An itemnum contains the option 
number of the desired information. The information is returned in the 
corresponding item or is stored using the item element as a pointer, depend- 
ing on the information desired. 
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CONDITION CODES 

CCE Successful call. All error codes set to zero. 

CCG Not used. 

CCL Unsuccessful call with errorcodes set accordingly. 



error i§ 


Meaning 


errarS 





successful execution — no error 





1 


insufficient copobility to return 
request information 


index of offending itemnum 


3 


required parameter address (other 
than "errorl") out of bounds 


not used 


4 


address bounds violation while 
processing on option 


index of offending itemnum 


5 


invalid item number 


index of offending itemnum 


6 


invalid pin number no information 
returned 


-1 


7 


unaseigned pin number 


-1 


a 


unpaired itemnum/item parameters 


index of offending itemnum/item 
pair 


Note 1: 


The process will abort if errorl paran 
intrinsic is called in split stack mode 


leter address is illegal or if the 


Note 2: 


If an error condition is detected while 
the index of the itemnum where the 
stored in error2. 


processing an information request, 
offending option was located is 



Figure 1 . Error Codes Returned Form PROCINFO 



19 



item # 



information returned 



10 



ignored 

process identification number of calling process 

process identification number of the father of the 
specified process 

number of sons of the specified process 
(direct descendants) 

number of descendants (both direct and indirect) 
of the specified process 

number of generations (number of levels in the 
process tree substructure) the specified process 
has including itself 

process identification numbers of all sons 
(direct descendants) 

process identification numbers of all descendants 
(both direct and indirect) 

priority number in the master queue of specified 
process 

state and activation information of the specified 
process 

program name where the specified process is cur- 
rently executing 



item 



ignored 

integer where PIN will be returned 

integer where PIN will be returned 

integer where the number of sons will be returned 



integer where the number of descendants will be 
returned 

integer where number of generations will be 
returned 



integer array where son PINs will be returned (see 
note 1) 

integer array where descendent PINs will be 
returned (see note 1) 

integer where the priority will be returned (same 
as word 1 of the GETPROCINFO intrinsic) 

logical where the information will be returned 
(same as word 2 of the GETPROCINFO intrinsic) 

byte array where the fully qualified program name 
will be stored (see note 2) 



Note 1: Some options return a variable number of PINs. In these cases item should be set by the calling process to 
point to an integer where the PINs will be returned. The first word of the array should be set by the calling 
process to indicate the array size in words. PINs will be stored into the array, one PIN per word, starting with 
the second word and continuing until the array is filled or all PINs have been returned. If the array is not filled, 
the remaining unused locations will be zeroed. 

Note 2: The byte array for the program name must be a minimum of 28 bytes long. The name will be returned in the 
form of "f.g.a" where "f" will be the local file name, "g" will be the group name, and "a" will be the account 
name of the file containing the program that the specified process is currently executing. The name will be 
returned left -justified with the unused locations filled with blanks. 

Note 3: If the calling process is executing in privileged mode, requests for information will be honored for any process. 
Otherwise, requests will be honored as follows: 

1. Complete information will be returned for sons of the calling process itself. 

2. Item ten will be returned only if the calling process has read access to the program file. 

3. Information returned for indirect descendants and processes directly above the calling process will be 
limited to items two through seven and ten only. 

Process handling capability will also be required for any user mode call unless the calling process is requesting 
information about itself. 



Figure 2. Information Options for PROCINFO 
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